Skip to main content

DH PROD Migration Guide

Refer to the following documents when performing migration activities:

2. Overview​

  • The DH Migration framework enables controlled migration of configuration, metadata, resources, and binaries between environments.

  • The migration process is designed to:

    • Support incremental migrations.
    • Generate comparison reports before applying changes.
    • Provide rollback mechanisms.
    • Maintain migration history through migration tracking tables.

3. Migration Components​

3.1 Migration Scripts​

The migration framework consists of the following four scripts:

  1. Source Extraction Script
  2. Destination Validation Script
  3. Migration Execution Script
  4. Rollback Script

Each script performs a specific function within the migration lifecycle.

3.2 DH Migration Tracking Table​

Migration tracking is supported from:

DH APP v5.14.10

The DHMigration table maintains the migration history and is used to support incremental migrations and rollback operations.

Column NamePossible ValuesDescription
MigrationIdIntegerUnique identifier for each migration record. Generated as MAX(MigrationId) + 1.
MigrationTypeFULL, INCREMENTALFULL: Extracts all available data.

INCREMENTAL: Extracts data between the last successful migration and the specified target date.
MigrationDateTimestampDate and time when the migration is executed.
MigrationFromDateTimestampFULL: Uses the default start date.

INCREMENTAL: Uses the previous migration's MigrationToDate as the start date.
MigrationToDateTimestampFULL: Migration execution date.

INCREMENTAL: User-specified target date.
FlowTypeTRANSFERRED, RECEIVED, ROLLBACK, REVERTEDRepresents the migration status throughout the migration lifecycle.
CreModTimeSystem TimestampTimestamp indicating when the migration record was inserted or updated.

3.2.1 FlowType Values​

ValueDescription
TRANSFERREDRecorded when the Extraction Script is executed on the source environment.
RECEIVEDRecorded after successful execution of the Migration Script on the destination environment.
ROLLBACKRecorded when a completed migration is rolled back on the destination environment.
REVERTEDRecorded when a transferred migration is reverted on the source environment.

Note

  • SIT environments typically contain TRANSFERRED or REVERTED records.
  • PROD environments typically contain RECEIVED or ROLLBACK records.
  • UAT environments may contain all four FlowType values.

3.3 Table Categories​

The migration framework supports three categories of tables.

Table TypeDescription
Staging TableStores incoming migration data temporarily and is primarily used for comparison report generation.
Main TableStores the active production data currently used by the application.
Backup TableStores the previous state of the Main Table to support rollback operations.

4. Migration Workflow​

Step 1 – Source Environment

Execute Script 1 on the source environment.

4.1.1 Activities Performed​

  • Extract migration data from the source database.

  • Insert a new record into the DHMigration table with status Transferred.

  • Create a migration package containing:

    • SH_PROGRAMS
    • SH_RESOURCES
    • seeds.sql

The generated migration package should then be transferred to the destination environment.

Step 2 – Destination Environment

Execute Script 2 on the destination environment.

4.2.1 Activities Performed​

  • Extract the migration package generated in Step 1.
  • Create staging tables.
  • Load migration data into the staging tables.
  • Generate a comparison report.

Step 3 – Comparison Report Validation

The generated comparison report must be reviewed and validated by the BSA Team.

4.3.1 Approved​

Proceed to Step 4.

4.3.2 Rejected​

Proceed to the rollback process.

Step 4 – Migration Execution

Execute Script 3 on the destination environment.

Activities Performed

4.4.1 Resource Backup​

Take a backup of:

  • SH_PROGRAMS
  • SH_RESOURCES

4.4.2 Resource Deployment​

Deploy the migrated binaries and resources.

4.4.3 Staging Cleanup​

Drop the staging tables created during comparison report generation.

4.4.4 Backup Cleanup​

Truncate the backup tables.

4.4.5 Main Table Processing​

For tables without Maker-Checker columns:

  • Truncate existing data.
  • Execute INSERT statements.

For Maker-Checker tables:

  • Execute UPSERT operations.

4.4.6 Migration Tracking​

Insert a new record into the DHMigration table with status:

RECEIVED

5. Rollback Procedures​

Rollback requirements depend on the migration stage.

5.1 Scenario 1 – Rollback Before Migration Execution​

5.1.1 Condition​

Migration is stopped after Script 2 and before Script 3.

5.1.2 Destination​

Execute the rollback script to:

  • Drop the staging tables.

5.1.3 Source​

Execute the rollback script to:

  • Update the latest Transferred record in DHMigration.
  • Change its status to:
REVERTED

5.2 Scenario 2 – Rollback After Migration Completion​

5.2.1 Condition​

Migration has completed successfully, but rollback is required due to post-migration issues.

5.2.2 Destination​

Execute the rollback script to:

  • Restore backup data.
  • Restore binaries and resources.
  • Update the latest Received record.

Migration status becomes:

ROLLBACK

5.2.3 Source​

Execute the rollback script to:

  • Update the latest Transferred record.

Migration status becomes:

REVERTED

6. Important Notes​

6.1 Environment Freeze​

Source and destination environments must remain frozen throughout the migration process.

No configuration changes should be performed while migration is in progress.

6.2 Rollback Tracking​

During rollback, the rollback script must always be executed on the source environment.

This ensures that future incremental migrations correctly determine the previous migration point.

6.3 Sequence Handling​

Database sequences are:

  • Dropped.
  • Recreated with the same current value as the source environment.

6.4 DH Settings​

When a matching key already exists in DHSettings:

  • The destination value is retained.

For newly introduced keys:

  • The value from the source environment is migrated.
  • Manual verification may be required after migration.

6.5 Incremental Migration Logic​

6.5.1 Insert Logic​

checkercretime > last_migration_date

6.5.2 Update Logic​

checkercretime < last_migration_date
AND checkermodtime > last_migration_date

Tables without Maker-Checker columns do not support incremental migration and always use INSERT statements.

6.6 SQL Script Types​

Two categories of SQL files are generated.

6.6.1 Staging SQL​

  • Insert-only statements.
  • Used for comparison report generation.

6.6.2 Main Table SQL​

  • INSERT statements.
  • UPDATE statements.

For UPDATE scripts:

  • modtime is updated to the current system timestamp.

For INSERT scripts:

  • Both cretime and modtime are set to the current system timestamp.

7. Script Execution​

For detailed information on:

  • Script execution
  • Supported arguments
  • Command syntax
  • Examples

Refer to:

8. DH Customer Repository​

Migration artifacts should be maintained within the DH Customer repository.

This includes:

  • Seed scripts
  • Resources
  • Binaries
  1. Store generated migration packages in the designated OneDrive location.
  2. Perform repository updates on a weekly basis.
  3. Push accumulated changes to the DH Customer repository.

For detailed instructions, refer to:

9. Binary Versions​

ComponentVersion
DH APIv6.1.4
dh_migrationv6.0.1
comparison_reportv6.1.1